#nullable enable
using Application.Core.Entity;

namespace Application.Service.Permissions;

/// <summary>
/// 权限管理服务接口
/// <para>功能：提供权限管理的Web API接口，支持权限信息的增删改查操作</para>
/// <list type="bullet">
/// <item><description>权限信息查询：获取所有权限、单个权限详情</description></item>
/// <item><description>权限管理：创建、更新、删除权限信息</description></item>
/// <item><description>权限编码管理：确保权限编码的唯一性</description></item>
/// <item><description>权限数据封装：为权限分配提供标准化的数据格式</description></item>
/// </list>
/// </summary>
public interface IPermissionService
{
    /// <summary>
    /// 查询系统中所有定义的权限信息
    /// </summary>
    /// <returns>返回包含所有权限信息的集合</returns>
    Task<IEnumerable<Permission>> GetAllAsync();

    /// <summary>
    /// 通过权限ID精确查询特定权限的详细信息
    /// </summary>
    /// <param name="permissionId">权限Id</param>
    /// <returns>返回指定权限的完整信息或null（权限不存在）</returns>
    Task<Permission?> GetAsync(int permissionId);

    /// <summary>
    /// 在系统中定义新的权限项
    /// </summary>
    /// <param name="dto">权限实体</param>
    /// <returns>返回创建权限、错误信息和创建的权限信息结果元组</returns>
    Task<(bool ok, string? error, Permission? value)> CreateAsync(Permission dto);

    /// <summary>
    /// 修改指定权限的基本信息和属性
    /// </summary>
    /// <param name="permissionId">权限Id</param>
    /// <param name="dto">权限实体</param>
    /// <returns>返回权限更新、错误信息和更新后的权限信息结果元组</returns>
    Task<(bool ok, string? error, Permission? value)> UpdateAsync(int permissionId, Permission dto);

    /// <summary>
    /// 从系统中永久删除指定权限及其相关数据
    /// </summary>
    /// <param name="permissionId">权限Id</param>
    /// <returns>预期结果：返回删除权限和错误信息结果元组</returns>
    Task<(bool ok, string? error)> DeleteAsync(int permissionId);
}